3D Graphics Programming with QuickDraw 3D 1.5.4

Custom Class Metahandlers

Any plug-in class that you define must have a metahandler. The metahandler is the method that the system uses to associate user-supplied routines with the required methods that a class needs to implement.

When you give a metahandler to QuickDraw 3D, it is called multiple times to build method tables and then is thrown away. You are guaranteed that your metahandler will never be called again after a call that was passed a metahandler returns.

Your metahandler should contain a switch on the methodType passed to it and should return the corresponding method as a TQ3XFunctionPointer . All return values from the metahandler are cast to this type.

typedef void (*TQ3FunctionPointer)(void);

A metahandler must always return a value. If it is passed a methodType that it does not understand, it must return NULL .

Generally a metahandler is implemented as one case statement. Certain types of classes, such as renderers, may have multiple levels of metahandlers.

TQ3MetaHandler

You must define an object metahandler to specify methods for custom object types or custom element types.



 
typedef unsigned long TQ3XMethodType;



 
typedef TQ3FunctionPointer (*TQ3MetaHandler) (

                     TQ3MethodType    methodType);

methodType: A method type.

DESCRIPTION

Your TQ3MetaHandler function should return a function pointer (a value of type TQ3FunctionPointer ) to the custom method whose type is specified by the methodType parameter. If you do not define a method of the specified type, your metahandler should return the value NULL .

In general, your metahandler should contain a switch statement that branches on the methodType parameter. QuickDraw 3D calls your metahandler repeatedly to build a method table when you first pass it to a QuickDraw 3D routine. Once QuickDraw 3D has finished building the method table, your metahandler is never called again.

When any one of your custom methods is called, you can be certain that your metahandler will not be called again.

EXAMPLE

This example of a metahandler is edited from the NameAttribute sample on the QuickDraw 3D SDK. It is essentially a big switch statement that maps a method type selector onto a function call for each implementation method. The default return value is NULL , so if the metahandler is called with a method type that is not recognised it returns NULL . All of the values are cast to type TQ3XFunctionPointer , even when they are not function pointers. For example, the return value for kQ3XMethodTypeObjectClassVersion is a long that has the version of the plug-in packed into it.



 
TQ3XFunctionPointer NameAttribute_MetaHandler(

    TQ3XMethodType      methodType)

{

    switch (methodType) {

        case kQ3XMethodTypeObjectClassVersion:

            return (TQ3XFunctionPointer)Q3_OBJECT_CLASS_VERSION(

                        majorVersion, minorVersion);

        case kQ3XMethodTypeObjectTraverse:

            return (TQ3XFunctionPointer) NameAttribute_Traverse;

        case kQ3XMethodTypeObjectReadData:

            return (TQ3XFunctionPointer) NameAttribute_ReadData;

        case kQ3XMethodTypeElementCopyAdd:

        case kQ3XMethodTypeElementCopyGet:

        case kQ3XMethodTypeElementCopyDuplicate:

            return (TQ3XFunctionPointer) NameAttribute_CopyAdd;

        case kQ3XMethodTypeElementCopyReplace:

            return (TQ3XFunctionPointer) NameAttribute_CopyReplace;

        case kQ3XMethodTypeElementDelete:

            return (TQ3XFunctionPointer) NameAttribute_Delete;

        default:

            return (TQ3XFunctionPointer) NULL;

    }

}